'\" t
.\
.\"
.TH "DISTROBOX" "1" "Nov 2025" "Distrobox" "User Manual"
.SH COMPATIBILITY
This project \f[B]does not need a dedicated image\f[R].
It can use any OCI images from docker\-hub, quay.io, or any registry of
your choice.
.PP
Many cloud images are stripped down on purpose to save size and may not
include commands such as \f[CR]which\f[R], \f[CR]mount\f[R],
\f[CR]less\f[R] or \f[CR]vi\f[R]).
Additional packages can be installed once inside the container.
We recommend using your preferred automation tool inside the container
if you find yourself having to repeatedly create new containers.
Maintaining your own custom image is also an option.
.PP
The main concern is having basic Linux utilities (\f[CR]mount\f[R]),
basic user management utilities (\f[CR]usermod, passwd\f[R]), and
\f[CR]sudo\f[R] correctly set.
.SS SUPPORTED CONTAINER MANAGERS
\f[CR]distrobox\f[R] can run on either \f[CR]podman\f[R],
\f[CR]docker\f[R] or \c
.UR https://github.com/89luca89/lilipod
\f[CR]lilipod\f[R]
.UE \c
.PP
It depends either on \f[CR]podman\f[R] configured in
\f[CR]rootless mode\f[R] or on \f[CR]docker\f[R] configured without sudo
(follow \c
.UR https://docs.docker.com/engine/install/linux-postinstall/
THESE instructions
.UE \c
)
.IP \[bu] 2
Minimum podman version: \f[B]2.1.0\f[R]
.IP \[bu] 2
Minimum docker client version: \f[B]19.03.15\f[R]
.IP \[bu] 2
Minimum lilipod version: \f[B]v0.0.1\f[R]
.PP
Follow the official installation guide here:
.IP \[bu] 2
\c
.UR https://podman.io/getting-started/installation
.UE \c
.IP \[bu] 2
\c
.UR https://docs.docker.com/engine/install
.UE \c
.IP \[bu] 2
\c
.UR https://docs.docker.com/engine/install/linux-postinstall/
.UE \c
.SS CONTAINERS DISTROS
Distrobox guests tested successfully with the following container
images:
.PP
.TS
tab(@);
lw(23.3n) lw(23.3n) lw(23.3n).
T{
Distro
T}@T{
Version
T}@T{
Images
T}
_
T{
AlmaLinux (Toolbox)
T}@T{
8  9
T}@T{
quay.io/toolbx\-images/almalinux\-toolbox:8 
quay.io/toolbx\-images/almalinux\-toolbox:9 
quay.io/toolbx\-images/almalinux\-toolbox:latest
T}
T{
Alpine (Toolbox)
T}@T{
3.16  3.17  3.18  3.19  3.20  edge
T}@T{
quay.io/toolbx\-images/alpine\-toolbox:3.16 
quay.io/toolbx\-images/alpine\-toolbox:3.17 
quay.io/toolbx\-images/alpine\-toolbox:3.18 
quay.io/toolbx\-images/alpine\-toolbox:3.19 
quay.io/toolbx\-images/alpine\-toolbox:3.20 
quay.io/toolbx\-images/alpine\-toolbox:edge 
quay.io/toolbx\-images/alpine\-toolbox:latest
T}
T{
AmazonLinux (Toolbox)
T}@T{
2  2022
T}@T{
quay.io/toolbx\-images/amazonlinux\-toolbox:2 
quay.io/toolbx\-images/amazonlinux\-toolbox:2023 
quay.io/toolbx\-images/amazonlinux\-toolbox:latest
T}
T{
Archlinux (Toolbox)
T}@T{
T}@T{
quay.io/toolbx/arch\-toolbox:latest
T}
T{
ALT Linux
T}@T{
p10  p11  sisyphus
T}@T{
docker.io/library/alt:p10  docker.io/library/alt:p11 
docker.io/library/alt:sisyphus
T}
T{
Bazzite Arch
T}@T{
T}@T{
ghcr.io/ublue\-os/bazzite\-arch:latest 
ghcr.io/ublue\-os/bazzite\-arch\-gnome:latest
T}
T{
Centos (Toolbox)
T}@T{
stream8  stream9
T}@T{
quay.io/toolbx\-images/centos\-toolbox:stream8 
quay.io/toolbx\-images/centos\-toolbox:stream9 
quay.io/toolbx\-images/centos\-toolbox:latest
T}
T{
Debian (Toolbox)
T}@T{
11  12  13  testing  unstable
T}@T{
quay.io/toolbx\-images/debian\-toolbox:11 
quay.io/toolbx\-images/debian\-toolbox:12 
quay.io/toolbx\-images/debian\-toolbox:13 
quay.io/toolbx\-images/debian\-toolbox:testing 
quay.io/toolbx\-images/debian\-toolbox:unstable 
quay.io/toolbx\-images/debian\-toolbox:latest
T}
T{
Fedora (Toolbox)
T}@T{
37  38  39  40  41  42  Rawhide
T}@T{
registry.fedoraproject.org/fedora\-toolbox:37 
registry.fedoraproject.org/fedora\-toolbox:38 
registry.fedoraproject.org/fedora\-toolbox:39 
registry.fedoraproject.org/fedora\-toolbox:40 
quay.io/fedora/fedora\-toolbox:41  quay.io/fedora/fedora\-toolbox:42 
quay.io/fedora/fedora\-toolbox:rawhide
T}
T{
openSUSE (Toolbox)
T}@T{
T}@T{
registry.opensuse.org/opensuse/distrobox:latest
T}
T{
RedHat (Toolbox)
T}@T{
8  9
T}@T{
registry.access.redhat.com/ubi8/toolbox 
registry.access.redhat.com/ubi9/toolbox
T}
T{
Rocky Linux (Toolbox)
T}@T{
8  9
T}@T{
quay.io/toolbx\-images/rockylinux\-toolbox:8 
quay.io/toolbx\-images/rockylinux\-toolbox:9 
quay.io/toolbx\-images/rockylinux\-toolbox:latest
T}
T{
Ubuntu (Toolbox)
T}@T{
16.04  18.04  20.04  22.04  24.04
T}@T{
quay.io/toolbx/ubuntu\-toolbox:16.04 
quay.io/toolbx/ubuntu\-toolbox:18.04 
quay.io/toolbx/ubuntu\-toolbox:20.04 
quay.io/toolbx/ubuntu\-toolbox:22.04 
quay.io/toolbx/ubuntu\-toolbox:24.04 
quay.io/toolbx/ubuntu\-toolbox:latest
T}
T{
Chainguard Wolfi (Toolbox)
T}@T{
T}@T{
quay.io/toolbx\-images/wolfi\-toolbox:latest
T}
T{
Ublue
T}@T{
bluefin\-cli  ubuntu\-toolbox  fedora\-toolbox  wolfi\-toolbox 
archlinux\-distrobox  powershell\-toolbox
T}@T{
ghcr.io/ublue\-os/bluefin\-cli  ghcr.io/ublue\-os/bluefin\-cli 
ghcr.io/ublue\-os/ubuntu\-toolbox  ghcr.io/ublue\-os/fedora\-toolbox 
ghcr.io/ublue\-os/wolfi\-toolbox  ghcr.io/ublue\-os/arch\-toolbox 
ghcr.io/ublue\-os/powershell\-toolbox
T}
T{
T}@T{
T}@T{
T}
T{
AlmaLinux
T}@T{
8  8\-minimal  9  9\-minimal
T}@T{
docker.io/library/almalinux:8  docker.io/library/almalinux:9
T}
T{
Alpine Linux
T}@T{
3.15  3.16  3.17  3.18  3.19  3.20  edge
T}@T{
docker.io/library/alpine:3.15  docker.io/library/alpine:3.16 
docker.io/library/alpine:3.17  docker.io/library/alpine:3.18 
docker.io/library/alpine:3.19  docker.io/library/alpine:3.20 
docker.io/library/alpine:edge  docker.io/library/alpine:latest
T}
T{
AmazonLinux
T}@T{
1  2  2023
T}@T{
public.ecr.aws/amazonlinux/amazonlinux:1 
public.ecr.aws/amazonlinux/amazonlinux:2 
public.ecr.aws/amazonlinux/amazonlinux:2023
T}
T{
Archlinux
T}@T{
T}@T{
docker.io/library/archlinux:latest
T}
T{
Blackarch
T}@T{
T}@T{
docker.io/blackarchlinux/blackarch:latest
T}
T{
CentOS Stream
T}@T{
8  9  10
T}@T{
quay.io/centos/centos:stream8  quay.io/centos/centos:stream9 
quay.io/centos/centos:stream10
T}
T{
Chainguard Wolfi
T}@T{
T}@T{
cgr.dev/chainguard/wolfi\-base:latest
T}
T{
Chimera Linux
T}@T{
T}@T{
docker.io/chimeralinux/chimera:latest
T}
T{
Crystal Linux
T}@T{
T}@T{
registry.gitlab.com/crystal\-linux/misc/docker:latest
T}
T{
Debian
T}@T{
7  8  9  10  11  12  13
T}@T{
docker.io/debian/eol:wheezy  docker.io/debian/eol:buster 
docker.io/debian/eol:bullseye 
docker.io/library/debian:bookworm\-backports 
docker.io/library/debian:stable\-backports
T}
T{
Debian
T}@T{
Testing
T}@T{
docker.io/library/debian:testing 
docker.io/library/debian:testing\-backports
T}
T{
Debian
T}@T{
Unstable
T}@T{
docker.io/library/debian:unstable
T}
T{
deepin
T}@T{
20 (apricot)  23 (beige)
T}@T{
docker.io/linuxdeepin/apricot  docker.io/linuxdeepin/deepin:beige
T}
T{
Fedora
T}@T{
36  37  38  39  40  41  42  Rawhide
T}@T{
quay.io/fedora/fedora:36  quay.io/fedora/fedora:37 
quay.io/fedora/fedora:38  quay.io/fedora/fedora:39 
quay.io/fedora/fedora:40  quay.io/fedora/fedora:41 
quay.io/fedora/fedora:42  quay.io/fedora/fedora:rawhide
T}
T{
Gentoo Linux
T}@T{
rolling
T}@T{
docker.io/gentoo/stage3:latest
T}
T{
KDE neon
T}@T{
Latest
T}@T{
invent\-registry.kde.org/neon/docker\-images/plasma:latest
T}
T{
Kali Linux
T}@T{
rolling
T}@T{
docker.io/kalilinux/kali\-rolling:latest
T}
T{
Mint
T}@T{
21.1
T}@T{
docker.io/linuxmintd/mint21.1\-amd64
T}
T{
Neurodebian
T}@T{
nd120
T}@T{
docker.io/library/neurodebian:nd120
T}
T{
openSUSE
T}@T{
Leap
T}@T{
registry.opensuse.org/opensuse/leap:latest
T}
T{
openSUSE
T}@T{
Tumbleweed
T}@T{
registry.opensuse.org/opensuse/distrobox:latest 
registry.opensuse.org/opensuse/tumbleweed:latest 
registry.opensuse.org/opensuse/toolbox:latest 
registry.opensuse.org/opensuse/distrobox\-bpftrace:latest
T}
T{
Oracle Linux
T}@T{
7  7\-slim  8  8\-slim  9  9\-slim
T}@T{
container\-registry.oracle.com/os/oraclelinux:7 
container\-registry.oracle.com/os/oraclelinux:7\-slim 
container\-registry.oracle.com/os/oraclelinux:8 
container\-registry.oracle.com/os/oraclelinux:8\-slim 
container\-registry.oracle.com/os/oraclelinux:9 
container\-registry.oracle.com/os/oraclelinux:9\-slim
T}
T{
RedHat (UBI)
T}@T{
7  8  9
T}@T{
registry.access.redhat.com/ubi7/ubi  registry.access.redhat.com/ubi8/ubi
\ registry.access.redhat.com/ubi8/ubi\-init 
registry.access.redhat.com/ubi8/ubi\-minimal 
registry.access.redhat.com/ubi9/ubi 
registry.access.redhat.com/ubi9/ubi\-init 
registry.access.redhat.com/ubi9/ubi\-minimal
T}
T{
Rocky Linux
T}@T{
8  8\-minimal  9
T}@T{
quay.io/rockylinux/rockylinux:8 
quay.io/rockylinux/rockylinux:8\-minimal 
quay.io/rockylinux/rockylinux:9  quay.io/rockylinux/rockylinux:latest
T}
T{
Slackware
T}@T{
T}@T{
docker.io/vbatts/slackware:current
T}
T{
SteamOS
T}@T{
T}@T{
ghcr.io/linuxserver/steamos:latest
T}
T{
Ubuntu
T}@T{
14.04  16.04  18.04  20.04  22.04  24.04
T}@T{
docker.io/library/ubuntu:14.04  docker.io/library/ubuntu:16.04 
docker.io/library/ubuntu:18.04  docker.io/library/ubuntu:20.04 
docker.io/library/ubuntu:22.04  docker.io/library/ubuntu:24.04
T}
T{
Vanilla OS
T}@T{
VSO
T}@T{
ghcr.io/vanilla\-os/vso:main
T}
T{
Void Linux
T}@T{
glibc  musl
T}@T{
ghcr.io/void\-linux/void\-glibc\-full:latest 
ghcr.io/void\-linux/void\-musl\-full:latest
T}
.TE
.PP
Images marked with \f[B]Toolbox\f[R] are tailored images made by the
community efforts in \c
.UR https://github.com/toolbx-images/images
toolbx\-images/images
.UE \c
, so they are more indicated for desktop use, and first setup will take
less time.
Note however that if you use a non\-toolbox preconfigured image, the
\f[B]first\f[R] \f[CR]distrobox\-enter\f[R] you\[cq]ll perform can take
a while as it will download and install the missing dependencies.
.PP
A small time tax to pay for the ability to use any type of image.
This will \f[B]not\f[R] occur after the first time, \f[B]subsequent
enters will be much faster.\f[R]
.PP
NixOS is not a supported container distro, and there are currently no
plans to bring support to it.
If you are looking for unprivileged NixOS environments, we suggest you
look into \c
.UR https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html
nix\-shell
.UE \c
\ or \c
.UR https://github.com/DavHau/nix-portable
nix portable
.UE \c
.SS NEW DISTRO SUPPORT
If your distro of choice is not on the list, open an issue requesting
support for it, we can work together to check if it is possible to add
support for it.
.PP
Or just try using it anyway, if it works, open an issue and it will be
added to the list!
.SS OLDER DISTRIBUTIONS
For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu 12.04,
compatibility is not assured.
.PP
Their \f[CR]libc\f[R] version is incompatible with kernel releases after
\f[CR]>=4.11\f[R].
A work around this is to use the \f[CR]vsyscall=emulate\f[R] flag in the
bootloader of the host.
.PP
Keep also in mind that mirrors could be down for such old releases, so
you will need to build a custom distrobox image to ensure basic
dependencies are met.
.SS GPU ACCELERATION SUPPORT
For Intel and AMD Gpus, the support is baked in, as the containers will
install their latest available mesa/dri drivers.
.PP
For NVidia, you can use the \f[CR]\-\-nvidia\f[R] flag during create,
see distrobox\-create documentation to discover how to use it.
.PP
Alternatively, you can use the nvidia\-container\-toolkit utility to set
up the integration independently from the distrobox\[cq]s own flag.
